Markdownでシーケンス図とかが書けるMermaid記法で業務フローを書いたら意外とイケたので自分なりのコツを紹介してみる

こんにちは、臼田です。

みなさん、業務設計してますか？(挨拶

今回はMarkdownでシーケンス図やフローチャートなどの図を記述できるMermaidを使って業務フローを書いてみたら、意外と書けたので自分なりのTipsを紹介したいと思います。

その前に

注意点として、まだMermaidを使い始めたばかりなので、「もっとこうしたらいいぞ」とか「こっちのほうがいいぞ」とかあれば建設的なフィードバックとしてSNSとかでいただけるとありがたいです。

あと業務フローって表現しましたが、人によって思い描く業務フローが違うと思うので、業務フローの定義に関するツッコミはご容赦ください。私が今回Mermaidで書いたのは以下の図です。(内容はブログ用に簡素化しました)

この図のコードは以下のとおりです。(後ほど解説します)

sequenceDiagram
    autonumber
    actor お客様
    participant form as 申し込みフォーム
    participant s3 as 申込書補保管S3
    participant admin as 管理システム
    お客様->>form: サービス申し込み
    Note left of form: 申込書
    form->>s3: 申込書保存
    Note left of s3: 申込書
    form->>お客様: 受付処理中連絡
    s3->>s3: FSSによる申込書マルウェアチェック
    s3->>admin: 申込書マルウェアチェック完了通知
    admin->>s3: 申込書取得リクエスト
    s3->>admin: 申込書取得レスポンス
    Note left of admin: 申込書
    admin->>admin: 申込書バリデーションチェック
    admin->>admin: 申込情報登録
    admin->>お客様: 受付完了連絡

Mermaidとは

MermaidはMarkdownの中でダイアグラムやチャートなどの図を記述できる記法(あるいや構文)です。詳細はこちらのページや以下のブログを見ていただくといいと思います。

最近ではGitHubでもMermaidに対応したので、話題になっていると思います。以下のブログも参考になります。

対応している図の種類も多く、以下に対応しています。

• フローチャート
• シーケンス図
• クラス図
• 状態遷移図
• ER図
• ジャーニーマップ
• ガントチャート
• パイチャート
• 要件図

例えばシーケンス図の短いデモでは以下の記述で図が出来上がります。

sequenceDiagram
    Alice->>;John: Hello John, how are you?
    John-->>;Alice: Great!
    Alice-)John: See you later!

シンプルな上、コードで図を管理することができるため色んな場面で活躍できると思います。

業務フローを書くときのTips

ここからは細かい話を流れ関係なく書いていきますのでご容赦を。

シーケンス図でフローを定義

冒頭に図を貼りましたが、この図はMermaidではsequenceDiagramの定義で作成しています。業務フローの大体はシーケンス図が適しているような気がしますが、複雑な判断などのフローがありフローチャートのほうが適している図を書きたくなったらflowchartを利用することもできます。その場合の記述方法はこちらが参考になります。以下はすべてシーケンス図での表現方法なのでご容赦を。

Noteでファイルのやり取りを表現

私が最初にMermaidで業務フローを書こうと思ったとき、ファイルのやり取りなどの表現がうまくできなさそうだなーと思いました。でもMermaidのドキュメントを読んでいたら意外と表現の幅が広いことに気づきました。

よくあるファイルの流れはNoteの記述で解決できそうでした。記法とその図は以下のとおりです。

sequenceDiagram
    お客様->>form: サービス申し込み
    Note left of form: 申込書

Noteで注釈を追記でき、[ right of | left of | over ]でその位置を定義できます。私はファイルを受け取る側の、矢印が来る方向に配置するようにしています。どの位置関係がいいかはルールを決めておいたほうが理解しやすそうです。

人とシステムを分けて表現する

Mermaidでは何も定義しなければやり取りする対象はプロセスとして四角く囲まれます。明示的にactorとして定義すると、人の形に変わります。人でないものはparticipantとして定義して対象が人なのか分かるようにすると直感的になります。

sequenceDiagram
    actor お客様
    participant form as 申し込みフォーム
    participant s3 as 申込書補保管S3

actorとparticipantを明示的に定義して理想の位置関係にする

上記の続きですが、Mermaidではactorとparticipantは記述した順番に左から右に並ぶようです。

明示的に定義しないと登場順に並べられるので、直感的に分かりやすいように位置関係を調整しましょう。

コードで書いてありますから、あとからずらすのも簡単です。うれしい。

自動採番はコードで図を管理するメリット

採番はautonumberと1行入れるだけです。自動的に番号を補完してくれるので更新する際も余計な手間がかかりません。

VSCodeで書くなら拡張機能を入れる

私は以下2つを入れています。お好みで使ってください。

• Markdown Preview Mermaid Support: プレビューできます
• Mermaid Markdown Syntax Highlighting: シンタックスハイライトできます

さいごに

業務に必要な図がコードで書けることは嬉しいですね。

どんどん書き方の知見が溜まって、みんなで簡単に図に手を入れられるようにしていければいいなーと思いました。

こんなやり方いいぜ！があればどしどし教えて下さい！